Properties
| | Property | Type | Access | Description |
|---|
| active | Boolean |
r/w | Set to true to make this window active.
• A modal dialog that is visible is by definition the active dialog.
• An active palette is the front-most window.
•
An active control is the one with focus'that is, the one that accepts keystrokes, or in the case of a Button, be selected when the user types Return or Enter.
|
| alignChildren | String |
r/w | Tells the layout manager how unlike-sized children of this container should be aligned within a column or row.
Order of creation determines which children are at the top of a column or the left of a row; the earlier a child is created, the closer it is to the top or left of its column or row. If defined, alignment for a child element overrides the alignChildren setting for the parent container. See alignment property for values.
|
| alignment | String |
r/w |
The alignment style for child elements of a container. If defined, this value overrides the alignChildren setting for the parent container.
This can be a single string, which indicates the alignment for the orientation specified in the parent container, or an array of two strings, indicating both the horizontal and vertical alignment (in that order). Allowed values depend on the orientation value of the parent container. They are not case sensitive.
•
For orientation=row:top, bottom, fill
•
For orientation=column: left, right, fill
•
For orientation=stack:top, bottom, left, right, fill
|
| bounds | Bounds |
r/w | The bounds of the window's drawable area, excluding the frame, in screen coordinates. |
| cancelElement | Object |
r/w |
For windows of type dialog, the UI element to notify when the user presses a cancellation key combination.
The cancellation key is the Esc key. By default, looks for a button whose name or text is "cancel" (case disregarded). |
| characters | Number (min: 0) |
r/w | A number of characters for which to reserve space when calculating the preferred size of the window. |
| children | Array of Object |
readonly | The collection of UI elements that have been added to this container.
An array indexed by number or by a string containing an element's name. The length property of this array is the number of child elements for container elements, and is zero for controls. |
| defaultElement | Object |
r/w |
For windows of type dialog, the UI element to notify when the user presses a Enter key.
By default, looks for a button whose name or text is "ok" (case disregarded). |
| enabled | Boolean |
r/w | True if this element is enabled.
An enabled element can accept input, according to its type. When false, control elements do not accept input, and all types of elements have a dimmed appearance. |
| frameBounds | Bounds |
readonly | The bounds of the window frame in screen coordinates.
The frame consists of the title bar and borders that enclose the content region of a window, depending on the windowing system. |
| frameLocation | Point |
r/w | The top left corner of the window frame in screen coordinates.
The same as [frameBounds.x, frameBounds.y]. Set this value to move the window frame to the specified location on the screen. The frameBounds value changes accordingly.
|
| frameSize | Dimension |
readonly | The size and location of the window's frame in screen coordinates. |
| graphics | ScriptUIGraphics |
readonly |
The graphics object that can be used to customize the window's appearance, in response to the onDraw event.
|
| helpTip | String |
r/w | The help text that is displayed when the mouse hovers over the element. |
| indent | Number (min: 0) |
r/w | The number of pixels to indent the element. |
| justify | String |
r/w | The default text justification style for child text elements. (default: left)
One of left, center, or right. Justification only works if this value is set on creation of the element.
|
| layout | LayoutManager |
r/w | The layout manager for this container.
The first time a container object is made visible, ScriptUI invokes this layout manager by calling its layout() function. Default is an instance of the LayoutManager class that is automatically created when the container element is created.
|
| location | Point |
r/w | The upper left corner of the window's drawable area.
The same as [bounds.x, bounds.y]. |
| margins | Number |
r/w | The number of pixels between the edges of a container and the outermost child elements.
You can specify different margins for each edge of the container. The default value is based on the type of container, and is chosen to match the standard Adobe UI guidelines. |
| maximized | Boolean |
r/w | True if the window is expanded. |
| maximumSize | Dimension |
r/w | The largest rectangle to which the window can be resized. |
| minimized | Boolean |
r/w | True if the window is minimized or iconified. |
| minimumSize | Dimension |
r/w | The smallest rectangle to which the window can be resized. |
| opacity | Number |
r/w | The opacity of the window, in the range [0..1]. (default: 1.0)
A value of 1.0 (the default) makes the window completely opaque, a value of 0 makes it completely transparent. Intermediate values make it partially transparent to any degree. |
| orientation | String |
r/w | The layout orientation of children in a container.
Interpreted by the layout manager for the container. The default LayoutManager Object accepts the (case-insensitive) values row, column, or stack. For window and panel, the default is column, and for group the default is row. The allowed values for the container's alignChildren and its children's alignment properties depend on the orientation.
|
| parent | Object |
readonly | The immediate parent element. |
| preferredSize | Dimension |
r/w | The preferred size of the window.
Used in automatic layout and resizing. To set a specific value for only one dimension, specify the other dimension as -1. |
| properties | Object |
r/w | An object that contains one or more creation properties of the container (properties used only when the element is created).
Creation properties of a Window object can include:
• resizeable: When true, the window can be resized by the user. Default is false.
• su1PanelCoordinates: Photoshop only. When true, the child panels of this window automatically adjust the positions of their children for compatability with Photoshop CS (in which the vertical coordinate was measured from outside the frame). Default is false. Individual panels can override the parent window's setting.
• closeButton: Bridge only. When true, the title bar includes a button to close the window, if the platform and window type allow it. When false, it does not. Default is true. Not used for dialogs.
• maximizeButton: Bridge only. When true, the title bar includes a button to expand the window to its maximum size (typically, the entire screen), if the platform and window type allow it. When false, it does not. Default is false for type palette, true for type window. Not used for dialogs.
|
| shortcutKey | String |
r/w |
The keypress combination that invokes this element's onShortcutKey() callback.
|
| size | Dimension |
r/w | The current size and location of the content area of the window in screen coordinates. |
| spacing | Number |
r/w | The number of pixels separating one child element from its adjacent sibling element.
Because each container holds only a single row or column of children, only a single spacing value is needed for a container. The default value is based on the type of container, and is chosen to match standard Adobe UI guidelines. |
| text | String |
r/w | The title, label, or displayed text, a localizeable string.
Does not apply to containers of type group. |
| type | String |
readonly | The element type; "dialog", "palette", or "window". |
| visible | Boolean |
r/w | When true, the element is shown, when false it is hidden.
When a container is hidden, its children are also hidden, but they retain their own visibility values, and are shown or hidden accordingly when the parent is next shown. |
| window | Window (SUI) |
readonly | The window that this element belongs to. |
| windowBounds | Bounds |
readonly | The bounds of this window relative to the top-level parent window. |
|
Methods
| Constructor Window (type:
String[, title:
String][, bounds:
Bounds][, properties:
Object])
Creates a new window.
| Parameter | Type | Description |
|---|
| type | String | The window type.
One of:
•
window: Creates a simple window that can be used as a main window for an application. (Not supported by Photoshop CS3.)
•
palette: Creates a modeless dialog, also called a floating palette. (Not supported by Photoshop CS3.)
•
dialog: Creates a modal dialog.
This argument can also be a ScriptUI resource specification; in that case, all other arguments are ignored.
|
| title | String | The window title, a localizable string. (Optional) |
| bounds | Bounds | The window's position and size. (Optional) |
| properties | Object | An object containing creation-only properties.
Can contain any of these properties:
•
resizeable: When true, the window can be resized by the user. Default is false.
•
su1PanelCoordinates: Photoshop only. When true, the child panels of this window automatically adjust the positions of their children for compatability with Photoshop CS (in which the vertical coordinate was measured from outside the frame). Default is false. Individual panels can override the parent window's setting.
•
: When true, the title bar includes a button to close the window, if the platform and window type allow it. When false, it does not. Default is true. Not used for dialogs.
•
maximizeButton: When true, the title bar includes a button to expand the window to its maximum size (typically, the entire screen), if the platform and window type allow it. When false, it does not. Default is false for type palette, true for type window. Not used for dialogs.
•
minimizeButton: When true, the title bar includes a button to minimize or iconify the window, if the platform and window type allow it. When false, it does not. Default is false for type palette, true for type window. Main windows cannot have a minimize button in Mac OS. Not used for dialogs.
•
independent: When true, a window of type window is independent of other application windows, and can be hidden behind them in Windows. In Mac OS, has no effect. Default is false.
•
borderless: When true, the window has no title bar or borders. Properties that control those features are ignored.
(Optional) |
Classvoid alert (message:
String[, title:
String][, errorIcon:
Boolean=false])
Displays a platform-standard dialog containing a short message and an OK button.
| Parameter | Type | Description |
|---|
| message | String | TThe string for the displayed message. |
| title | String | A string to appear as the title of the dialog, if the platform supports a title.
Ignored in Mac OS, which does not support titles for alert dialogs. The default title string is "Script Alert". (Optional) |
| errorIcon | Boolean | When true, the platform-standard alert icon is replaced by the platform-standard error icon in the dialog. (default: false)
Ignored in Mac OS, which does not support icons for alert dialogs. |
Boolean confirm (message:
String[, noAsDefault:
Boolean=false][, title:
String])
Displays a platform-standard dialog containing a short message and two buttons labeled Yes and No.
Returns true if the user clicked Yes, false if the user clicked No.
| Parameter | Type | Description |
|---|
| message | String | The string for the displayed message. |
| noAsDefault | Boolean | When true, the No button is the default choice, selected when the user types Enter. (default: false)
Default is false, meaning that Yes is the default choice. |
| title | String | A string to appear as the title of the dialog, if the platform supports a title.
Ignored in Mac OS, which does not support titles for alert dialogs. The default title string is "Script Alert". (Optional) |
Window find (type:
String, title:
String)
Use this method to find an existing window.
This includes windows defined by ScriptUI resource strings, windows already created by a script, and windows created by the application (if the application supports this case). This function is not supported by all applications. Returns a Window object found or generated from the resource, or null if no such window or resource exists.
| Parameter | Type | Description |
|---|
| type | String | The name of a predefined resource available to JavaScript in the current application; or the window type.
If a title is specified, the type is used if more than one window with that title is found. Can be null or the empty string. |
| title | String | The window title. |
String prompt (prompt:
String[, default:
String][, title:
String])
Displays a modal dialog that returns the user's text input.
Returns the value of the text edit field if the user clicked OK, null if the user clicked Cancel.
| Parameter | Type | Description |
|---|
| prompt | String | The string for the displayed message. |
| default | String | The initial value to be displayed in the text edit field. (Optional) |
| title | String | A string to appear as the title of the dialog.
In Windows, this appears in the window's frame; in Mac OS it appears above the message. The default title string is "Script Prompt". (Optional) |
Eventsvoid onActivate ()
An event-handler callback function, called when the window acquires the keyboard focus.
Called when the user gives the window the keyboard focus by clicking it or otherwise making it the active window.
Boolean onClose ()
An event-handler callback function, called when the window is about to be closed.
Called when a request is made to close the window, either by an explicit call to the close() function or by a user action (clicking the OS-specific close icon in the title bar). The function is called before the window actually closes; it can return false to cancel the close operation.
void onDeactivate ()
An event-handler callback function, called when the window loses the keyboard focus.
Called when the user moves the keyboard focus from the previously active window to another window.
void onMove ()
An event-handler callback function, called when the window has been moved
void onMoving ()
An event-handler callback function, called when the window is being moved
Called while a window in being moved, each time the position changes. A handler can monitor the move operation.
void onResize ()
An event-handler callback function, called after the window has been resized
void onResizing ()
An event-handler callback function, called while a window is being resized
Called while a window is being resized, each time the height or width changes. A handler can monitor the resize operation.
void onShortcutKey ()
In Windows only, an event-handler callback function, called a shortcut-key sequence is typed that matches the shortcutKey value for this window.
void onShow ()
An event-handler callback function, called just before the window is displayed
Called when a request is made to open the window using the show() method, before the window is made visible, but after automatic layout is complete. A handler can modify the results of the automatic layout.
InstancesObject add (type:
String[, bounds:
Bounds][, text:
String][, properties:
Object])
Creates and returns a new control or container object and adds it to the children of this window.
| Parameter | Type | Description |
|---|
| type | String |
The type of the child element, as specified for the type property.
Control types are listed in the JavaScript Tools Guide.
|
| bounds | Bounds | A bounds specification that describes the size and position of the new control or container, relative to its parent.
If supplied, this value creates a new Bounds object which is assigned to the new object's bounds property.
(Optional) |
| text | String | The text or label, a localizable string.
Initial text to be displayed in the control as the title, label, or contents, depending on the control type. If supplied, this value is assigned to the new object's text property.
(Optional) |
| properties | Object | An object that contains one or more creation properties of the new child (properties used only when the element is created).
The creation properties depend on the element type. See
property of each control type.
(Optional) |
Boolean addEventListener (eventName:
String, handler:
Function[, capturePhase:
Boolean=false])
Registers an event handler for a particular type of event occuring in this window.
| Parameter | Type | Description |
|---|
| eventName | String | The name of the event.
Predefined event names are: change, changing, move, moving, resize, resizing, show , enterKey, focus, blur, keydown, keyup, mousedown, mouseup, mousemove, mouseover, mouseout, click (detail = 1 for single, 2 for double). |
| handler | Function | The function that handles the event.
This can be the name of a function defined in the extension, or a locally defined handler function to be executed when the event occurs. A handler function takes one argument, the UIEvent object.
|
| capturePhase | Boolean | When true, the handler is called only in the capturing phase of the event propagation. (default: false)
Default is false, meaning that the handler is called in the bubbling phase if this object is an ancestor of the target, or in the at-target phase if this object is itself the target. (Optional) |
void center ([window:
Window])
Centers this window on screen or with repect to another window.
| Parameter | Type | Description |
|---|
| window | Window (SUI) | The relative window. If not specified, centers on the screen. (Optional) |
void close ([return:
Any])
Closes this window.
. If an onClose() callback is defined for the window, calls that function before closing the window.
| Parameter | Type | Description |
|---|
| return | Any | A number to be returned from the show() method that invoked this window as a modal dialog. (Optional) |
UIEvent dispatchEvent ()
Simulates the occurrence of an event in this target.
A script can create a UIEvent object for a specific event and pass it to this method to start the event propagation for the event.
void hide ()
Hides this windows.
When a window is hidden, its children are also hidden, but when it is shown again, the children retain their own visibility states.
• For a modal dialog, closes the dialog and sets its result to 0.
void notify ([eventName:
String])
Sends a notification message to all listeners, simulating the specified user interaction event.
| Parameter | Type | Description |
|---|
| eventName | String | The event name; if omitted, the default event is sent.
One of: onClose, onMove, onMoving, onResize, onResizing, onShow
(Optional) |
void remove (what:
Any)
Removes the specified child control from this window's children array.
No error results if the child does not exist.
| Parameter | Type | Description |
|---|
| what | Any |
The child control to remove, specified by 0-based index, text property value, or as a control object.
|
Boolean removeEventListener (eventName:
String, handler:
Function[, capturePhase:
Boolean=false])
Unregisters an event handler for a particular type of event occuring in this window.
All arguments must be identical to those that were used to register the event handler.
| Parameter | Type | Description |
|---|
| eventName | String | The name of the event. |
| handler | Function | The function that handles the event. |
| capturePhase | Boolean | Whether to call the handler only in the capturing phase of the event propagation. (default: false) |
void show ()
Makes this window visible.
If an onShow() callback is defined for a window, calls that function before showing the window.When a window or container is hidden, its children are also hidden, but when it is shown again, the children retain their own visibility states.
• For a modal dialog, opens the dialog and does not return until the dialog is dismissed. If it is dismissed via the close() method, this method returns any result value passed to that method. Otherwise, returns 0.
|